home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / SCSL / dtrevc.z / dtrevc
Encoding:
Text File  |  2002-10-03  |  9.4 KB  |  265 lines
  1.  
  2.  
  3.  
  4. DDDDTTTTRRRREEEEVVVVCCCC((((3333SSSS))))                                                          DDDDTTTTRRRREEEEVVVVCCCC((((3333SSSS))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      DTREVC - compute some or all of the right and/or left eigenvectors of a
  10.      real upper quasi-triangular matrix T
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      SUBROUTINE DTREVC( SIDE, HOWMNY, SELECT, N, T, LDT, VL, LDVL, VR, LDVR,
  14.                         MM, M, WORK, INFO )
  15.  
  16.          CHARACTER      HOWMNY, SIDE
  17.  
  18.          INTEGER        INFO, LDT, LDVL, LDVR, M, MM, N
  19.  
  20.          LOGICAL        SELECT( * )
  21.  
  22.          DOUBLE         PRECISION T( LDT, * ), VL( LDVL, * ), VR( LDVR, * ),
  23.                         WORK( * )
  24.  
  25. IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
  26.      These routines are part of the SCSL Scientific Library and can be loaded
  27.      using either the -lscs or the -lscs_mp option.  The -lscs_mp option
  28.      directs the linker to use the multi-processor version of the library.
  29.  
  30.      When linking to SCSL with -lscs or -lscs_mp, the default integer size is
  31.      4 bytes (32 bits). Another version of SCSL is available in which integers
  32.      are 8 bytes (64 bits).  This version allows the user access to larger
  33.      memory sizes and helps when porting legacy Cray codes.  It can be loaded
  34.      by using the -lscs_i8 option or the -lscs_i8_mp option. A program may use
  35.      only one of the two versions; 4-byte integer and 8-byte integer library
  36.      calls cannot be mixed.
  37.  
  38. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  39.      DTREVC computes some or all of the right and/or left eigenvectors of a
  40.      real upper quasi-triangular matrix T. The right eigenvector x and the
  41.      left eigenvector y of T corresponding to an eigenvalue w are defined by:
  42.  
  43.                   T*x = w*x,     y'*T = w*y'
  44.  
  45.      where y' denotes the conjugate transpose of the vector y.
  46.  
  47.      If all eigenvectors are requested, the routine may either return the
  48.      matrices X and/or Y of right or left eigenvectors of T, or the products
  49.      Q*X and/or Q*Y, where Q is an input orthogonal
  50.      matrix. If T was obtained from the real-Schur factorization of an
  51.      original matrix A = Q*T*Q', then Q*X and Q*Y are the matrices of right or
  52.      left eigenvectors of A.
  53.  
  54.      T must be in Schur canonical form (as returned by DHSEQR), that is, block
  55.      upper triangular with 1-by-1 and 2-by-2 diagonal blocks; each 2-by-2
  56.      diagonal block has its diagonal elements equal and its off-diagonal
  57.      elements of opposite sign.  Corresponding to each 2-by-2 diagonal block
  58.      is a complex conjugate pair of eigenvalues and eigenvectors; only one
  59.      eigenvector of the pair is computed, namely the one corresponding to the
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. DDDDTTTTRRRREEEEVVVVCCCC((((3333SSSS))))                                                          DDDDTTTTRRRREEEEVVVVCCCC((((3333SSSS))))
  71.  
  72.  
  73.  
  74.      eigenvalue with positive imaginary part.
  75.  
  76.  
  77. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  78.      SIDE    (input) CHARACTER*1
  79.              = 'R':  compute right eigenvectors only;
  80.              = 'L':  compute left eigenvectors only;
  81.              = 'B':  compute both right and left eigenvectors.
  82.  
  83.      HOWMNY  (input) CHARACTER*1
  84.              = 'A':  compute all right and/or left eigenvectors;
  85.              = 'B':  compute all right and/or left eigenvectors, and
  86.              backtransform them using the input matrices supplied in VR and/or
  87.              VL; = 'S':  compute selected right and/or left eigenvectors,
  88.              specified by the logical array SELECT.
  89.  
  90.      SELECT  (input/output) LOGICAL array, dimension (N)
  91.              If HOWMNY = 'S', SELECT specifies the eigenvectors to be
  92.              computed.  If HOWMNY = 'A' or 'B', SELECT is not referenced.  To
  93.              select the real eigenvector corresponding to a real eigenvalue
  94.              w(j), SELECT(j) must be set to .TRUE..  To select the complex
  95.              eigenvector corresponding to a complex conjugate pair w(j) and
  96.              w(j+1), either SELECT(j) or SELECT(j+1) must be set to .TRUE.;
  97.              then on exit SELECT(j) is .TRUE. and SELECT(j+1) is .FALSE..
  98.  
  99.      N       (input) INTEGER
  100.              The order of the matrix T. N >= 0.
  101.  
  102.      T       (input) DOUBLE PRECISION array, dimension (LDT,N)
  103.              The upper quasi-triangular matrix T in Schur canonical form.
  104.  
  105.      LDT     (input) INTEGER
  106.              The leading dimension of the array T. LDT >= max(1,N).
  107.  
  108.      VL      (input/output) DOUBLE PRECISION array, dimension (LDVL,MM)
  109.              On entry, if SIDE = 'L' or 'B' and HOWMNY = 'B', VL must contain
  110.              an N-by-N matrix Q (usually the orthogonal matrix Q of Schur
  111.              vectors returned by DHSEQR).  On exit, if SIDE = 'L' or 'B', VL
  112.              contains:  if HOWMNY = 'A', the matrix Y of left eigenvectors of
  113.              T; VL has the same quasi-lower triangular form as T'. If T(i,i)
  114.              is a real eigenvalue, then the i-th column VL(i) of VL  is its
  115.              corresponding eigenvector. If T(i:i+1,i:i+1) is a 2-by-2 block
  116.              whose eigenvalues are complex-conjugate eigenvalues of T, then
  117.              VL(i)+sqrt(-1)*VL(i+1) is the complex eigenvector corresponding
  118.              to the eigenvalue with positive real part.  if HOWMNY = 'B', the
  119.              matrix Q*Y; if HOWMNY = 'S', the left eigenvectors of T specified
  120.              by SELECT, stored consecutively in the columns of VL, in the same
  121.              order as their eigenvalues.  A complex eigenvector corresponding
  122.              to a complex eigenvalue is stored in two consecutive columns, the
  123.              first holding the real part, and the second the imaginary part.
  124.              If SIDE = 'R', VL is not referenced.
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. DDDDTTTTRRRREEEEVVVVCCCC((((3333SSSS))))                                                          DDDDTTTTRRRREEEEVVVVCCCC((((3333SSSS))))
  137.  
  138.  
  139.  
  140.      LDVL    (input) INTEGER
  141.              The leading dimension of the array VL.  LDVL >= max(1,N) if SIDE
  142.              = 'L' or 'B'; LDVL >= 1 otherwise.
  143.  
  144.      VR      (input/output) DOUBLE PRECISION array, dimension (LDVR,MM)
  145.              On entry, if SIDE = 'R' or 'B' and HOWMNY = 'B', VR must contain
  146.              an N-by-N matrix Q (usually the orthogonal matrix Q of Schur
  147.              vectors returned by DHSEQR).  On exit, if SIDE = 'R' or 'B', VR
  148.              contains:  if HOWMNY = 'A', the matrix X of right eigenvectors of
  149.              T; VR has the same quasi-upper triangular form as T. If T(i,i) is
  150.              a real eigenvalue, then the i-th column VR(i) of VR  is its
  151.              corresponding eigenvector. If T(i:i+1,i:i+1) is a 2-by-2 block
  152.              whose eigenvalues are complex-conjugate eigenvalues of T, then
  153.              VR(i)+sqrt(-1)*VR(i+1) is the complex eigenvector corresponding
  154.              to the eigenvalue with positive real part.  if HOWMNY = 'B', the
  155.              matrix Q*X; if HOWMNY = 'S', the right eigenvectors of T
  156.              specified by SELECT, stored consecutively in the columns of VR,
  157.              in the same order as their eigenvalues.  A complex eigenvector
  158.              corresponding to a complex eigenvalue is stored in two
  159.              consecutive columns, the first holding the real part and the
  160.              second the imaginary part.  If SIDE = 'L', VR is not referenced.
  161.  
  162.      LDVR    (input) INTEGER
  163.              The leading dimension of the array VR.  LDVR >= max(1,N) if SIDE
  164.              = 'R' or 'B'; LDVR >= 1 otherwise.
  165.  
  166.      MM      (input) INTEGER
  167.              The number of columns in the arrays VL and/or VR. MM >= M.
  168.  
  169.      M       (output) INTEGER
  170.              The number of columns in the arrays VL and/or VR actually used to
  171.              store the eigenvectors.  If HOWMNY = 'A' or 'B', M is set to N.
  172.              Each selected real eigenvector occupies one column and each
  173.              selected complex eigenvector occupies two columns.
  174.  
  175.      WORK    (workspace) DOUBLE PRECISION array, dimension (3*N)
  176.  
  177.      INFO    (output) INTEGER
  178.              = 0:  successful exit
  179.              < 0:  if INFO = -i, the i-th argument had an illegal value
  180.  
  181. FFFFUUUURRRRTTTTHHHHEEEERRRR DDDDEEEETTTTAAAAIIIILLLLSSSS
  182.      The algorithm used in this program is basically backward (forward)
  183.      substitution, with scaling to make the the code robust against possible
  184.      overflow.
  185.  
  186.      Each eigenvector is normalized so that the element of largest magnitude
  187.      has magnitude 1; here the magnitude of a complex number (x,y) is taken to
  188.      be |x| + |y|.
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. DDDDTTTTRRRREEEEVVVVCCCC((((3333SSSS))))                                                          DDDDTTTTRRRREEEEVVVVCCCC((((3333SSSS))))
  203.  
  204.  
  205.  
  206. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  207.      INTRO_LAPACK(3S), INTRO_SCSL(3S)
  208.  
  209.      This man page is available only online.
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.